<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Chapter 4. Concurrency</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Getting Started with Berkeley DB Transaction Processing" />
    <link rel="up" href="index.html" title="Getting Started with Berkeley DB Transaction Processing" />
    <link rel="prev" href="maxtxns.html" title="Configuring the Transaction Subsystem" />
    <link rel="next" href="blocking_deadlocks.html" title="Locks, Blocks, and Deadlocks" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Chapter 4. Concurrency</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="maxtxns.html">Prev</a> </td>
          <th width="60%" align="center"> </th>
          <td width="20%" align="right"> <a accesskey="n" href="blocking_deadlocks.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="chapter" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title"><a id="txnconcurrency"></a>Chapter 4. Concurrency</h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <p>
          <b>Table of Contents</b>
        </p>
        <dl>
          <dt>
            <span class="sect1">
              <a href="txnconcurrency.html#concurrenthandles">Which DB Handles are Free-Threaded</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="blocking_deadlocks.html">Locks, Blocks, and Deadlocks</a>
            </span>
          </dt>
          <dd>
            <dl>
              <dt>
                <span class="sect2">
                  <a href="blocking_deadlocks.html#locks">Locks</a>
                </span>
              </dt>
              <dt>
                <span class="sect2">
                  <a href="blocking_deadlocks.html#blocks">Blocks</a>
                </span>
              </dt>
              <dt>
                <span class="sect2">
                  <a href="blocking_deadlocks.html#deadlocks">Deadlocks</a>
                </span>
              </dt>
            </dl>
          </dd>
          <dt>
            <span class="sect1">
              <a href="lockingsubsystem.html">The Locking Subsystem</a>
            </span>
          </dt>
          <dd>
            <dl>
              <dt>
                <span class="sect2">
                  <a href="lockingsubsystem.html#configuringlock">Configuring the Locking Subsystem</a>
                </span>
              </dt>
              <dt>
                <span class="sect2">
                  <a href="lockingsubsystem.html#configdeadlkdetect">Configuring Deadlock Detection</a>
                </span>
              </dt>
              <dt>
                <span class="sect2">
                  <a href="lockingsubsystem.html#deadlockresolve">Resolving Deadlocks</a>
                </span>
              </dt>
              <dt>
                <span class="sect2">
                  <a href="lockingsubsystem.html#setpriority">Setting Transaction Priorities</a>
                </span>
              </dt>
            </dl>
          </dd>
          <dt>
            <span class="sect1">
              <a href="isolation.html">Isolation</a>
            </span>
          </dt>
          <dd>
            <dl>
              <dt>
                <span class="sect2">
                  <a href="isolation.html#degreesofisolation">Supported Degrees of Isolation</a>
                </span>
              </dt>
              <dt>
                <span class="sect2">
                  <a href="isolation.html#dirtyreads">Reading Uncommitted Data</a>
                </span>
              </dt>
              <dt>
                <span class="sect2">
                  <a href="isolation.html#readcommitted">Committed Reads</a>
                </span>
              </dt>
              <dt>
                <span class="sect2">
                  <a href="isolation.html#snapshot_isolation">Using Snapshot Isolation</a>
                </span>
              </dt>
            </dl>
          </dd>
          <dt>
            <span class="sect1">
              <a href="txn_ccursor.html">Transactional Cursors and Concurrent Applications</a>
            </span>
          </dt>
          <dd>
            <dl>
              <dt>
                <span class="sect2">
                  <a href="txn_ccursor.html#cursordirtyreads">Using Cursors with Uncommitted Data</a>
                </span>
              </dt>
            </dl>
          </dd>
          <dt>
            <span class="sect1">
              <a href="exclusivelock.html">Exclusive Database Handles</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="readmodifywrite.html">Read/Modify/Write</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="txnnowait.html">No Wait on Blocks</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="reversesplit.html">Reverse BTree Splits</a>
            </span>
          </dt>
        </dl>
      </div>
      <p>

        DB offers a great deal of support for multi-threaded
            <span>
                and multi-process
            </span>
        applications even when transactions are not in use. Many of DB's
        handles are 
        thread-safe<span>, or 
        can be made thread-safe by providing the appropriate flag at handle creation time,</span> 
        and DB provides a
        flexible locking subsystem for managing databases in a concurrent
        application. Further, DB provides a robust mechanism for
        detecting and responding to 
        <span>deadlocks</span>
        . 
        All of these concepts are
        explored in this chapter.
     </p>
      <p>
        Before continuing, it is useful to define a few terms that will appear
        throughout this chapter:
     </p>
      <div class="itemizedlist">
        <ul type="disc">
          <li>
            <p>
                <span class="emphasis"><em>Thread of control</em></span>
            </p>
            <p>
                Refers to a thread that is performing work in your application.
                Typically, in this book that thread will be performing DB
                operations.
            </p>
            <p>
                Note that this term can also be taken to mean a separate process
                that is performing work — DB supports multi-process
                operations on your databases.
            </p>
            <p>
                Also, DB is agnostic with regard to the type or style of
                threads in use in your application. So if you are using
                multiple threads
                (as opposed to multiple processes) to perform concurrent
                database access, you are free to use whatever thread package is
                best for your platform and application. That said, this manual
                will use pthreads for its threading examples because those have
                the best chance of being supported across a large range of
                platforms.
            </p>
          </li>
          <li>
            <p>
                <span class="emphasis"><em>Locking</em></span>
            </p>
            <p>
                When a thread of control obtains 
                access to a shared resource, it is said to be
                <span class="emphasis"><em>locking</em></span> that resource. Note that
                DB supports both exclusive and non-exclusive locks. See
                <a class="xref" href="blocking_deadlocks.html#locks" title="Locks">Locks</a> for more information.
            </p>
          </li>
          <li>
            <p>
                <span class="emphasis"><em>Free-threaded</em></span>
            </p>
            <p>
                Data structures and objects are free-threaded if they can be
                shared across threads of control without any explicit locking on
                the part of the application.  Some books, libraries, and
                programming languages may use the term
                <span class="emphasis"><em>thread-safe</em></span> for data structures or objects
                that have this characteristic. The two terms mean the
                same thing.
            </p>
            <p>
                For a description of free-threaded DB objects, see
                <a class="xref" href="txnconcurrency.html#concurrenthandles" title="Which DB Handles are Free-Threaded">Which DB Handles are Free-Threaded</a>.
            </p>
          </li>
          <li>
            <p>
                <span class="emphasis"><em>Blocked</em></span>
            </p>
            <p>
                When a thread cannot obtain a lock because some other
                thread already holds a lock on that object, the lock
                attempt is said to be <span class="emphasis"><em>blocked</em></span>. See
                <a class="xref" href="blocking_deadlocks.html#blocks" title="Blocks">Blocks</a> for more information.
            </p>
          </li>
          <li>
            <p>
                <span class="emphasis"><em>Deadlock</em></span>
            </p>
            <p>
                Occurs when two or more threads of control attempt to access conflicting resource in such a way as none
                of the threads can any longer make further progress.
            </p>
            <p>
                For example, if Thread A is blocked waiting for a resource held by Thread
                B, while at the same time Thread B is blocked waiting for a
                resource held by Thread A, then neither thread can make any
                forward progress. In this situation, Thread A and Thread B
                are said to be <span class="emphasis"><em>deadlocked.</em></span>
            </p>
            <p>
                For more information, see <a class="xref" href="blocking_deadlocks.html#deadlocks" title="Deadlocks">Deadlocks</a>.
            </p>
          </li>
        </ul>
      </div>
      <div class="sect1" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a id="concurrenthandles"></a>Which DB Handles are Free-Threaded</h2>
            </div>
          </div>
        </div>
        <p>
            The following describes to what extent and under what conditions
            individual handles are free-threaded.
        </p>
        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>
                   <code class="classname">DB_ENV</code> 
                    
                    
                   
                </p>
              <p>
                    Free-threaded so long as
                        <span>
                            the <code class="literal">DB_THREAD</code> flag is provided to
                            the environment <code class="methodname">open()</code>
                            method.
                        </span>
                        
                </p>
            </li>
            <li>
              <p>
                   <code class="classname">DB</code> 
                    
                    
                   
                </p>
              <p>
                    Free-threaded so long as
                        <span>
                            the <code class="literal">DB_THREAD</code> flag is provided to
                            the database <code class="methodname">open()</code>
                            method, or if the database is opened using a
                            free-threaded environment handle.
                        </span>
                        
                </p>
            </li>
            <li>
              <p>
                   <code class="classname">DBC</code> 
                    
                    
                   
                </p>
              <p>
                    Cursors are not free-threaded. However, they
                    can be used by multiple threads of control so 
                    long as the application serializes access to the handle.
                </p>
            </li>
            <li>
              <p>
                   <code class="classname">DB_TXN</code> 
                    
                    
                    
                </p>
              <p>
                    Access must be serialized by the application across threads of control.
                </p>
            </li>
          </ul>
        </div>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="maxtxns.html">Prev</a> </td>
          <td width="20%" align="center"> </td>
          <td width="40%" align="right"> <a accesskey="n" href="blocking_deadlocks.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Configuring the Transaction Subsystem </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Locks, Blocks, and Deadlocks</td>
        </tr>
      </table>
    </div>
  </body>
</html>
